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Please read the tutorial “Preparing for 
Programming” prior to attempting the 
exercise contained in this tutorial. 
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Introduction 
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First, let's go over the important steps in the process of writing an Icy-based 
program and putting it to work: 


¢ Understand the geometry problem. 


¢ Identify the set of SPICE kernels that contain the data needed to perform the 
computation. 


¢ Select the SPICE APIs needed to compute the quantities of interest. 
¢ Write and compile the program. 


¢ Get actual kernel files and verify that they contain the data needed to support 
the computation for the time(s) of interest. 


¢ Run the program. 


To illustrate these steps, let's write a program that computes the apparent | 
intersection of the boresight ray of a given CASSINI science instrument with the 
surface of a given Saturnian satellite. The program will compute: 


¢ Planetocentric and planetodetic (geodetic) latitudes and longitudes of the 
intercept point. 


¢ Range from spacecraft to intercept point. 
¢ Illumination angles (phase, solar incidence, and emission) at the intercept point. 
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Observation geometry 
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We want the boresight on-board clock ephemeris time UTC time 
~ 


intercept on the surface, range < 

from s/c to intercept, and 

illumination angles at ‘nsttliment inertial frame 
the intercept point. irame 


surface normal 


When? time (UTC, TDB or TT) 5 


sp ace craft 


On what object? satnm ne 


In what frame? __ fixref 
For which instrument? instnm 
For what spacecraft? scnm 


Using what model? setupf 
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Shapes of satellites, planets 


Ephemerides for spacecraft, we 
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Which Kernels are Needed? 
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Data required to compute vectors, rotations and other parameters shown in 
the picture are stored in the SPICE kernels listed below. 


Note: these kernels have been selected to support this presentation; they should not be assumed to be 


appropriate for user applications. 


Parameter 


time conversions 


satellite orientation 
satellite shape 
satellite position 


planet barycenter position 
spacecraft position 
spacecraft orientation 
instrument alignment 
instrument boresight 
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Kernel Type 
generic LSK 
CASSINI SCLK 
CASSINI PCK 
CASSINI PCK 
planet/sat 
ephemeris SPK 
planet SPK 
spacecraft SPK 
spacecraft CK 
CASSINI FK 
Instrument IK 
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The easiest and most flexible way to make these kernels available to the program is 
via cspice_furnsh. For this example we make a setup file (also called a “metakernel” 
or “furnsh kernel”) containing a list of kernels to be loaded: 


Note: these kernels have been selected to support this presentation; they 
should not be assumed to be appropriate for user applications. 


\begindata 


KERNELS TO LOAD = ( 


\begintext 


and we make the program prompt for the name of this setup file: 


read, setupf, PROMPT='Enter setup file name > ' 
cspice furnsh, setupf 
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Programming Solution 
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¢ Prompt for setup file (“metakernel”) name; load kernels specified via setup 
file. (Done on previous chart.) 


¢ Prompt for user inputs required to completely specify problem. Obtain 
further inputs required by geometry routines via Icy calls. 


¢ Compute the intersection of the boresight direction ray with the surface of 
the satellite, presented as a triaxial ellipsoid. 


If there is an intersection, 
Convert Cartesian coordinates of the intersection point to planetocentric 
latitudinal and planetodetic coordinates 
«Compute spacecraft-to-intercept point range 
¢Find the illumination angles (phase, solar incidence, and emission) at 
the intercept point 


¢ Display the results. 


We discuss the geometric portion of the problem first. 
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Compute surface intercept 
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Compute the intercept point (point) of the boresight vector (insite) specified in 
the instrument frame (iframe) of the instrument mounted on the spacecraft (scnm) 
with the surface of the satellite (satnm) at the TDB time of interest (et) in the 
satellite’s body-fixed frame (fixref). This call also returns the light-time 
corrected epoch at the intercept point (trgepc), the spacecraft-to-intercept point 
vector (srfvec), and a flag indicating whether the intercept was found (found). 

We use "converged Newtonian" light time plus stellar aberration corrections to 
produce the most accurate surface intercept solution possible. We model the 
surface of the satellite as an ellipsoid. 


cspice sincpt, 'Ellipsoid', satnm, et, fixref, 'CN+S', scnm, iframe, $ 
insite, point, trgepc, srfvec, found 


The range we want is obtained from the outputs of cspice_sincpt. These 
outputs are defined only if a surface intercept is found. If found is true, the 
spacecraft-to-surface intercept range is the norm of the output argument srfvec. 
Units are km. We use the Icy function cspice_vnorm to obtain the norm: 


cspice vnorm( srfvec ) 


We'll write out the range data along with the other program results. 
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ompute Lat/Lon and Illumination Angles 
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Compute the planetocentric latitude (pclat) and longitude (pclon), as well as 
the planetodetic latitude (pdlat) and longitude (pdlon) of the intersection 
point. 


if ( found ) then begin 
cspice reclat, point, r, pclon, pclat 


;; Let re, rp, and £ be the satellite's longer equatorial 
;; vadius, polar radius, and flattening factor. 


re = radii[0] 
rp = radii[2] 
£ = (re- xp) / re; 


cspice recgeo, point, re, f, pdlon, pdlat, alt 


Ly illumination angles we want are the outputs of cspice_ilumin. Units are 
radians. 


cspice ilumin, 'Ellipsoid', satnm, et, fixref, 'CN+S', scnm, $ 
point, trgepc, srfvec, phase, solar, emissn 
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Geometry Calculations: Summary 
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;; Compute the boresight ray intersection with the surface of the 
;; target body. 


cspice sincpt, 'Ellipsoid', satnm, et, fixref, 'CN+S', scnm, § 
iframe, insite, point, trgepc, srfvec, found 


;; If an intercept is found, compute planetocentric and planetodetic 
;; latitude and longitude of the point. 


if ( found ) then begin 
cspice reclat, point, r, pclon, pclat 
;; Let re, rp, and £ be the satellite's longer equatorial 
;; vadius, polar radius, and flattening factor. 


re = radii[0] 
rp = radii[2] 
f = (xre- rp) / re; 


cspice recgeo, point, re, f, pdlon, pdlat, alt 
;; Compute illumination angles at the surface point. 


cspice ilumin, 'Ellipsoid', satnm, et, fixref, 'CN+S', scnm, $ 
point, trgepc, srfvec, phase, solar, emissn 


endif else begin 
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Get inputs - 1 
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The code above used quite a few inputs that we don't have yet: 


¢ TDB epoch of interest (et ); 

¢ satellite and s/c names (satnm, scnm); 

¢ satellite body-fixed frame name (fixref); 

¢ satellite ellipsoid radii (cadii); 

¢ instrument fixed frame name (iframe); 

¢ instrument boresight vector in the instrument frame (insite); 


Some of these values are user inputs; others can be obtained via Icy calls 
once the required kernels have been loaded. 


Let's prompt for the satellite name (satnn), satellite frame name (fixref), 
spacecraft name (scnm), instrument name (instnm) and time of interest (time): 


y 


read, satnm , PROMPT='Enter satellite name 
read, fixref, PROMPT='Enter satellite frame 
read, scnm , PROMPT='Enter spacecraft name 
read, instnm, PROMPT='Enter instrument name 
read, time , PROMPT='Enter time 


7 


VV VVYV 
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Get Inputs - 2 
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Then we can get the rest of the inputs from Icy calls: 


To get the TDB epoch (et) from the user-supplied time string (which may 
refer to the UTC, TDB or TT time systems): 


cspice str2et, time, et 
To get the satellite’s ellipsoid radii (radii): 
cspice bodvrd, satnm, "RADII", 3, radii 


To get the instrument boresight direction (insite) and the name of the 
instrument frame (iframe) in which it is defined: 


cspice getfvn, instnm, ROOM, shape, iframe, insite, bundry 
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Getting inputs: summary 
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;; Prompt for the user-supplied inputs for our program 
read, setupf, PROMPT='Enter setup file name > ’ 


cspice furnsh, setupf 


read, satnm , PROMPT='Enter satellite name > ’ 
read, fixref, PROMPT='Enter satellite frame > ’ 
read, scnm , PROMPT='Enter spacecraft name > ' 
read, instnm, PROMPT='Enter instrument name > ' 
read, time , PROMPT='Enter time > ! 


;; Get the epoch corresponding to the input time: 
cspice str2et, time, et 


;; Get the radii of the satellite. 


cspice bodvrd, satnm, "RADII", 3, radii 


;; Get the instrument boresight and frame name. 


cspice getfvn, instnm, ROOM, shape, iframe, insite, bundry 
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;; Display results. Convert angles from radians to degrees for output. 


print 
print, 


print, 
print, 
print, 
print, 
print, 
print, 


print, 
endif else 
print, 


endelse 
END 
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Display results 
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"Intercept planetocentric longitude (deg): ', $ 
cspice dpr()*pclon 

"Intercept planetocentric latitude (deg): ', $ 
cspice dpr()*pclat 

"Intercept planetodetic longitude (deg) : aa 
cspice dpr() *pdlon 

"Intercept planetodetic latitude (deg): ', $ 
cspice dpr()*pdlat 

"Range from spacecraft to intercept point (km): ', § 
cspice vnorm(srfvec) 

"Intercept phase angle (deg): ', $ 
cspice dpr() *phase 

"Intercept solar incidence angle (deg): ', $ 
cspice dpr()*solar 

"Intercept emission angle (deg) : ty. 


cspice dpr() *emissn 


begin 
"No intercept point found at ' + time 
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Complete the program 
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To finish up the program we need to declare the variables we've used. 


¢ We'll highlight techniques used by NAIF programmers 
¢ Add remaining IDL code required to make a syntactically valid program 


PRO PROG GEOMETRY 


ROOM 
setupf 
satnm 
fixref 
scnm 
instnm 
time 
R2D 


10L 


cspice dpr() 
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Complete source code - 1 


Navigation and Ancillary Information Facility 


;; Prompt for the user-supplied inputs for our program. 


read, setupf, 


PROMPT='Enter setup file name > ' 


cspice furnsh, setupf 


read, satnm , 
read, fixref, 
read, scnm _ , 
read, instnm, 
read, time _ , 


PROMPT='Enter satellite name 
PROMPT='Enter satellite frame 
PROMPT='Enter spacecraft name 
PROMPT='Enter instrument name 
PROMPT='Enter time 


VVVVYV 


;; Get the epoch corresponding to the input time: 
cspice str2et, time, et 


;; Get the radii of the satellite. 
cspice bodvrd, satnm, 'RADII', 3, radii 


;; Get the instrument boresight and frame name. 


cspice getfvn, instnm, ROOM, shape, iframe, insite, bundry 
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Complete source code - 2 
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;; Compute the boresight ray intersection with the surface of the 

;; target body. 

cspice sincpt, 'Ellipsoid', satnm, et, fixref, 'CN+S', scnm, $ 
iframe, insite, point, trgepc, srfvec, found 


If an intercept is found, compute planetocentric and planetodetic 
;; latitude and longitude of the point. 
if ( found ) then begin 
cspice reclat, point, r, pclon, pclat 
;; Let re, rp, and £ be the satellite's longer equatorial 
;; vadius, polar radius, and flattening factor. 
re = radii[0] 
= radii[2] 
£f = (re- rp) / re 
cspice recgeo, point, re, f, pdlon, pdlat, alt 


ee 
77 


K 
'O 
| 


;; Compute illumination angles at the surface point. 
cspice ilumin, 'Ellipsoid', satnm, et, fixref, 'CN+S', scnm, $ 
point, trgepc, srfvec, phase, solar, emissn 


;; Display results. Convert angles from radians to degrees 


;; £or output. 
print 
print, 'Intercept planetocentric longitude (deg): ', §$ 


R2D*pclon 
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Complete source code - 3 
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print, 'Intercept planetocentric latitude (deg): ', $ 
R2D*pclat 

print, 'Intercept planetodetic longitude (deg): ', $ 
R2D*pdlon 

print, 'Intercept planetodetic latitude (deg): ', $ 
R2D*pdlat 

print, 'Range from spacecraft to intercept point (km): ', §$ 
cspice vnorm(srfvec) 

print, 'Intercept phase angle (deg): ', § 
R2D*phase 

print, 'Intercept solar incidence angle (deg) : i. & 
R2D*solar 

print, 'Intercept emission angle (deg): ', $ 
R2D*emissn 


endif else begin 
print, 'No intercept point found at ' + time 
endelse 


;; Unload the kernels and clear the kernel pool 


cspice kclear 
END 
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Compile the program - 1 
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Though IDL functions in a manner similar to interpreted languages, it does 
compile source files to a binary form. 


Ensure that both the Icy Toolkit, and an IDL installation are properly installed. 
IDL must load the Icy DLM, icy.dlm/icy.so(dll) to compile those scripts 
containing Icy calls. IDL loads DLMs from default locations and from the 
current directory when the user ran IDL. The user may also explicitly load a 
DLM with the dim register command. 


Now compile the code. 
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1DL> 


Compile the program - 2 
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Terminal Window 


.compile prog geometry.pro 


Compiled module: PROG GEOMETRY. 
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Running the program 
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It looks like we have everything taken care of: 


¢ We have all necessary kernels 


¢ We made a setup file (metakernel) pointing to them 


¢ We wrote the program 


¢ We compiled the program 


Let's run it. 
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ED 
Ein 
Ein 
Bin 
Ein 
Bin 
Ein 


in 


in 


in 


in 


in 


in 
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Running the program 
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Terminal Window 


L> prog geometry 


i 
_ 
po 
_ 
_ 


pa 


i 


tercep 


_ 


tercep 


_ 


tercep 


pa 


tercep 


pa 


tercep 


_ 


tercep 


_ 


Intercept 


program 


ter time 


pa 


UL 


_ 


Cc 


_ 


Cc 


i 


UL 


pa 


UL 


_ 


C 


_ 


ter setup file name setup.ker 

ter satellite name PHOEBE 

Ler salellaite frame IAU_ PHOEBE 

ter spacecraft name CASSINI 

Ler instrument name CASSINI_ ISS NAC 


2004. yn LL Less 2200 


planetocentric longitude 
planetocentric latitude 
planetodetic longitude 
planetodetic latitude 

Range from spacecraft to intercept point 


phase angle 
solar incidence angle 
emission angle 


394843719 
4.1958778 
29403 119 
5.0480106 
2069.1697 
202139479 
18.247220 
cI OG ore cre Os, 
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Backup 
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¢ Latitude definitions: 


— Planetocentric latitude of a point P: angle between segment from 
origin to point and x-y plane (red arc in diagram). 


— Planetodetic latitude of a point P: angle between x-y plane and 
extension of ellipsoid normal vector N that connects x-y plane and 
P (blue arc in diagram). 


z-axis 


Reference ellipsoid 


Planetocentric 
latitude 


Planetodetia 
latitude 


O x-y plane 
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